home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / grafik / bildanzeiger / xanim2 / xanim.readme < prev    next >
Text File  |  1995-03-09  |  34KB  |  859 lines

  1.  
  2. XAnim Rev 2.69.7  22Sep94
  3.  
  4. COMPILING ON UNIX Systems (SunOS,Solaris,HP/UX,DG/UX,AIX,
  5.                Linux,Ultrix,OSF/1,etc)
  6.  
  7.  
  8.   If you have Imake on your system you can type
  9.  
  10.     xmkmf
  11.  
  12.   which should produce a Makefile from the Imakefile. Then
  13.   you can type:
  14.  
  15.     make xanim
  16.   
  17.   If this doesn't work you can copy Makefile.unx to Makefile.
  18.   Edit the Makefile and specify where the X11 includes and 
  19.   X11 libraries are on your particular machine. Then type
  20.  
  21.     make xanim
  22.  
  23.   NOTE: That in the Imakefile, XCOMM is used as a comment. This
  24.   is recommended by X11R6, but may break older revs. To fix,
  25.   simply replace every occurence of "XCOMM" with "#" in the
  26.   Imakefile. See top of Imakefile for more details.
  27.  
  28.  
  29. COMPILING ON VMS/AXP Systems
  30.   The files make.com and xanimXX.opt are provided for VMS users.
  31.   make.com should correctly detect wether you're running
  32.   DECWindows XUI or DECWindows MOTIF(revs 1.1 and 1.2) and use
  33.   the appropriate xanimXX.opt file.
  34.  
  35.   If you use the VMS MMS (or "make") facility, then a descript.mms
  36.   file is provided.
  37.  
  38.   NOTE: since VMS is case insensitve, all options to xanim must be
  39.   enclosed in double quotes in order for them to be proper recognized.
  40.   Example:
  41.         xanim "+bCn" anim1 anim2
  42.  
  43.  
  44. HOW TO USE XANIM
  45. The following is a copy of the man page with examples at the end.
  46.  
  47. SYNOPSIS
  48.      xanim [ +Vnum ] [ +Aaopts ]  [  +Ccopts  ]  [  +Ggopts  ]  [
  49.           +Mmopts  ] [ +Ssopts ] [ +opts ] animfile [ [ +opts ] [
  50.           animfile ] ... ]
  51.  
  52. DESCRIPTION
  53.      XAnim is a program that can display  animations  of  various
  54.      formats on systems running X11. XAnim currently supports the
  55.      following animation types:
  56.  
  57.       +  FLI animations.
  58.       +  FLC animations.
  59.       +  IFF animations.  The  following  features  are  sup-
  60.          ported:
  61.            -> Compressions 3,5,7,J(movies) and l(small L).
  62.            -> Color cycling during single images and anims.
  63.            -> Display Modes: depth 1-8, EHB, HAM and HAM8.
  64.       +  GIF87a and GIF89a files.
  65.            -> single and multiple images supported.
  66.            -> GIF89a animation extensions supported.
  67.       +  GIF89a animation extension support.
  68.       +  a kludgy text file listing gifs and  what  order  to
  69.          show them in.
  70.       +  DL animations. Formats 1, 2 and 3. TEMPORARILY DISABLED.
  71.       +  Amiga PFX(PageFlipper Plus F/X) animations. DISABLED TEMPORARILY.
  72.       +  Amiga MovieSetter animations(For those Eric Schwartz
  73.          fans).
  74.       +  Utah Raster Toolkit RLE images and anims.
  75.       +  AVI animations. Currently supported are
  76.            ->*IBM Ultimotion     (ULTI) depth 16.
  77.            -> Microsoft Video 1  (CRAM) depth 8 and 16.
  78.            -> SuperMac Cinepak   (CVID) depth 24.
  79.            -> Uncompressed       (RGB ) depth 8
  80.            -> Run length encoded (RLE8) depth 8.
  81.       +  Quicktime Animations.  The  following  features  are
  82.          supported:
  83.            -> Uncompressed     (RAW ) depth 4,8,16,24,24+ and GRAY 4,8.
  84.            -> Apple Graphics   (RLE ) depth 1,8,16 and 24 and GRAY 8.
  85.            -> Apple Animation  (SMC ) depth 8 and GRAY.
  86.            -> Apple Video      (RPZA) depth 16.
  87.            -> SuperMac Cinepak (CVID) depth 24 and GRAY 8.
  88.            -> ???      YUV2    (YUV2) depth 24.
  89.            -> Supports multiple video trak's.
  90.            -> Supports animations with multiple codecs.
  91.            -> Supports single-fork and separate .rsrc and .data forks.
  92.       +  any combination of the above  on  the  same  command
  93.          line.
  94.  
  95. ---------------------------------------------------------------------------
  96. * The following copyright applies to all Ultimotion segments of the code:
  97.  
  98.   "Copyright International Business Machines Corporation 1994, All rights
  99.    reserved. This product uses Ultimotion(tm) IBM video technology."
  100. ---------------------------------------------------------------------------
  101.  
  102.      XAnim also provides various options that allow the  user  to
  103.      alter colormaps, playback speeds, looping modes and can pro-
  104.      vide on-the-fly scaling of animations with the mouse.
  105.  
  106. OPTIONS
  107.      A + will generally turn an option on and a -  will  turn  an
  108.      option  off.   This  can  be  reversed at compile time. (see
  109.      xanim_config.h).
  110.  
  111.      In each SubMenu, the options can be  run  together  with  no
  112.      intervening spaces. In the list of SubMenu options presented
  113.      below, the first letter given is the letter  that  specifies
  114.      the  SubMenu  and  should NOT be repeated if several SubMenu
  115.      options are to be run together.
  116.  
  117.      For example,  "+Cn  +Cs10  +CF4"  can  also  be  written  as
  118.      "+Cns10F4" or "+CF4s10n".
  119.  
  120.      A + or a - within a SubMenu will be an exit from  that  sub-
  121.      menu.   Options  will  affect  all  animations following the
  122.      invocation of that option. Some options may  be  changed  in
  123.      between animations without affecting previous animations.
  124.  
  125.      In the following sections,  an  "num"  represents  an  integer
  126.      number and an "fnum" represents a floating point number. Don't
  127.      include the double quotes. If a floating point number is of an 
  128.      integer amount, the "." need not be specified. There should be
  129.      no spaces between the option and the numbers.
  130.  
  131.      aopts SubMenu for Audio Options
  132.       +Ae        Audio Enable. XAnim will ignore audio data if
  133.             this option is not used.
  134.  
  135.       +Ak        This option allows XAnim to skip video frames
  136.             in order to help keep video in sync with audio.
  137.             default is on.
  138.  
  139.       +As"fnum"    Scale Audio playback speed by "fnum". Only the
  140.             range 0.125 to 8.00 is allowed.
  141.             NOTE: CURRENTLY VIDEO DOESN'T SCALE WITH AUDIO.
  142.  
  143.       +Ap"num"    This turns a hardware specific Audio port on or off.
  144.                Port 0 - main speaker (on  by default)
  145.                Port 1 - headphones   (off by default)
  146.                Port 2 - line out     (not supported yet)
  147.  
  148.       +Av"num"    Sets the inital Audio Volume(0-100) with 0
  149.             the lowest. default is 40.
  150.  
  151.      copts SubMenu for Color Options
  152.  
  153.       +C1        Create a colormap from the  first  frame  of  a
  154.             TrueColor  anim  and  then  remap the remaining
  155.             frames to this colormap. This  can  potentially
  156.             add  significant time to the startup of an ani-
  157.             mation but usually results  in  better  colors.
  158.             The  animation  needs  to  be buffered for this
  159.             option to work.  Not  valid  for  TrueColor  or
  160.             DirectColor displays(nor is it needed).
  161.  
  162.       +C3        Convert TrueColor  anims  to  332(StaticColor).
  163.             TrueColor  anims  are  animations  that provide
  164.             separate RGB info for each pixel,  rather  than
  165.             each  pixel being an index into a global color-
  166.             map. AVI(16bit CRAM), QT(RPZA and RLE depth  16
  167.             and  24)  and URT RLE 24 bit anims are examples
  168.             of TrueColor anims. This option is ignored  for
  169.             TrueColor or DirectColor displays.
  170.  
  171.       +CA         Create  a  colormap  from  each  frame   of   a
  172.             TrueColor  anim.  This  can  be  useful  if the
  173.             colors radically change during  the  course  of
  174.             the  animation.  This can take a VERY,VERY long
  175.             time at start up. Animation must  be  buffered.
  176.             This   option   is  ignored  for  TrueColor  or
  177.             DirectColor displays.
  178.  
  179.       +Ca         Remap all images to  single  new  cmap  created
  180.             from all of the colormaps.
  181.  
  182.       +Cd         Use Floyd-Steinberg  dithering  if  needed  for
  183.             non-monochrome  displays.   This  will  cause a
  184.             reduction in playback speed.
  185.  
  186.       +Cf         Forcibly remap to all  frames  to  1st  frame's
  187.             cmap.
  188.  
  189.       +CF0          Turns off CF4 option.
  190.  
  191.       +CF4          This option samples the colors of true color
  192.             animations ahead of time and forms a color
  193.             lookup table.  Beats the just truncating to a
  194.             RGB 332 color table and IMHO beats dithering.
  195.             See the +s option below(also in copts submenu).
  196.  
  197.       +Cg         Convert TrueColor anims  to  gray  scale.  This
  198.             option is ignored for TrueColor and DirectColor
  199.             displays.
  200.  
  201.       +Ch         Use histogram to aid in color  reduction.  His-
  202.             trogramming  is  only  done  on frames that are
  203.             buffered.
  204.  
  205.       +Cm         This option is currently needed if you want  to
  206.             dither  TrueColor anims to a 332 colormap. Ani-
  207.             mation must be buffered.  Typically  +bC3dm  is
  208.             the  option  to  use. This can take a VERY long
  209.             time at start up.
  210.  
  211.       +Cn         Don't create new colormap but instead  allocate
  212.             colors from the X11 Display's default cmap.
  213.  
  214.       +Cs"num"    This is the number of frames the +CF4 option looks
  215.             at ahead of time. More frames potentially yields
  216.             better colors results, but takes more time at
  217.             start up.  default is 5.
  218.  
  219.      gopts SubMenu for Gamma Options
  220.  
  221.       +Ga"fnum"    Set gamma of animation to be displayed.
  222.  
  223.       +Gd"fnum"    Set gamma of display. 1.0 is no change. gamma's
  224.             greater  than 1.0 typically brighten the anima-
  225.             tion.
  226.  
  227.      mopts SubMenu for Median-Cut Quantization Options
  228.  
  229.       +Ma        compute box color from average of box.
  230.  
  231.       +Mc        compute box color as center of box.
  232.  
  233.       +Mb"num"    Truncate rgb to "num" bits before quantizing.
  234.  
  235.      sopts SubMenu for Scaling Options
  236.  
  237.       +Si        Half the  height  of  IFF  anims  if  they  are
  238.             interlaced.(Not  completely  reliable since not
  239.             all IFF anims correctly identify themselves  as
  240.             interlaced).
  241.  
  242.       +Sn        Prevents X11  window  from  resizing  to  match
  243.             animations's size.
  244.  
  245.       +Sr        Allow user to  resize  animation  on  the  fly.
  246.             Enlarging an animation can greatly reduce play-
  247.             back speed depending on the power of the cpu.
  248.  
  249.       +Ss"fnum"    Scale the size  of  animation  by  "fnum"  before
  250.             displaying.
  251.  
  252.       +Sh"fnum"    Scale the horizontal size of the  animation  by
  253.             "fnum" before displaying.
  254.  
  255.       +Sv"fnum"    Scale the vertical size  of  the  animation  by
  256.             "fnum" before displaying.
  257.  
  258.       +Sx"num"    Scale the animation to have  width  "num"  before
  259.             displaying.
  260.  
  261.       +Sy"num"    Scale the animation to have height  "num"  before
  262.             displaying.
  263.  
  264.       +Sc        Copy display scaling factors to display buffer-
  265.             ing factors.
  266.  
  267.       +SS"fnum"    Scale the size of the animation by "fnum"  before
  268.             buffering it.
  269.  
  270.       +SH"fnum"    Scale the horizontal size of the  animation  by
  271.             "fnum" before buffering it.
  272.  
  273.       +SV"fnum"    Scale the vertical size  of  the  animation  by
  274.             "fnum" before buffering it.
  275.  
  276.       +SX"num"    Scale the animation to have  width  "num"  before
  277.             buffering it.
  278.  
  279.       +SY"num"    Scale the animation to have height  "num"  before
  280.             buffering it.
  281.  
  282.       +SC        Copy buffer scaling factors to display  scaling
  283.             factors.
  284.  
  285.      Normal Options
  286.  
  287.       +b        Uncompress and buffer images before displaying.
  288.             This only applies to AVI,QT, IFF,FLI,FLC anima-
  289.             tions. The rest(GIF87a,GIF89a,DL,PFX  and  RLE)
  290.             are currently always uncompressed and buffered.
  291.             This is cleared by the +f option.
  292.  
  293.       +B        Used X11 Shared Memory(if present)for unbuffered
  294.             animations only.(This is mutually exclusive with
  295.             +b above).
  296.  
  297.       +f        Don't load anim into memory, but read each sec-
  298.             tion  only  when needed. This is supported only
  299.             for AVI,QT,IFF,FLI  and  FLC  animations.  This
  300.             option  is cleared by the +b option. This saves
  301.             memory at the cost of speed.
  302.  
  303.       +c        let xanim know that iff anim  is  a  nonlooping
  304.             one.
  305.  
  306.       +d"num"    debug switch. "num" can be from 0(off) to 5(most)
  307.             for level of detail.
  308.  
  309.       +F        Floyd-Steinberg dithering when needed.
  310.  
  311.       +j"num"    "num"  is  the  number  of  milliseconds  between
  312.             frames.  if  0  then  the time specified in the
  313.             animation is used for timing purposes.
  314.  
  315.       +l"num"    loop animation "num" number of times before  mov-
  316.             ing on to next animation.
  317.  
  318.       +lp"num"    ping-pong animation "num" number of times  before
  319.             moving on to next animation.
  320.  
  321.       +N        don't display images. Useful for benchmarking.
  322.  
  323.       +o        turns    on    certain    optimizations.    See
  324.             xanim.readme.
  325.  
  326.       +p        Use Pixmap instead of Image in X11. This option
  327.             has    no    effect   if   the   animation   is
  328.             buffered(either  by  default  or  with  the  +b
  329.             option).
  330.  
  331.       +r        Allow color cycling for IFF single images.
  332.  
  333.       +R        Allow color cycling  for  IFF  anims.  (default
  334.             should be off)
  335.  
  336.       +T0        Title option 0. Title is just XAnim.
  337.  
  338.       +T1        Title option 1. Title  is  current  anim  name.
  339.             When  anim is stopped, the current frame number
  340.             is included.
  341.  
  342.       +T2        Title option 2. Title is current anim name  and
  343.             current frame number.
  344.  
  345.       +v        Verbose mode. Gives some information about ani-
  346.             mation such as size, number of frames, etc.
  347.  
  348.       +V"num"    Select X11 Visual to use when displaying anima-
  349.             tion.  The  "num"  is  obtained  by  using the +X
  350.             option of xanim.
  351.  
  352.       +Vclass    Select the best X11 Visual of Class class  when
  353.             displaying  the  animation. class can be anyone
  354.             of the following strings and is  case  insensi-
  355.             tive. (ie StaTicGraY is same as staticgray).
  356.  
  357.             staticgray    Select best StaticGray Visual.
  358.             grayscale     Select best GrayScale Visual.
  359.             staticcolor   Select best StaticColor Visual.
  360.             pseudocolor   Select best PseudoColor Visual.
  361.             truecolor     Select best TrueColor Visual.
  362.             directcolor   Select best DirectColor Visual.
  363.  
  364.       +X        X11 verbose mode. Display information about the
  365.             support X11 visuals.
  366.  
  367.       +Ze        XAnim will exit after playing  through  command
  368.             line once.
  369.  
  370.       +Zp"num"    XAnim pause at frame "num" and then wait for user
  371.             input.  Several  pauses  may be specified. Each
  372.             group of pauses will only affect the  animation
  373.             immediately following them on the command line.
  374.             Pauses will occur at least once.
  375.  
  376.  
  377.  
  378. WINDOW COMMANDS
  379.      Once the animation is up and running there are various  com-
  380.      mands  that  can  be entered into that animation window from
  381.      the keyboard.
  382.  
  383.      q         quit.
  384.  
  385.      Q         Quit.
  386.  
  387.      g         Stop color cycling.
  388.  
  389.      r         Restore original Colors(useful after g).
  390.  
  391.      w         Restore original window size(useful  after  resiz-
  392.            ing).
  393.  
  394.      <space>   Toggle. starts/stops animation.
  395.  
  396.      ,         Single step back one frame.
  397.  
  398.      .         Single step forward one frame.
  399.  
  400.      <         Go back to start of previous anim.
  401.  
  402.      >         Go forward to start of next anim.
  403.  
  404.      m         Single step back one frame staying within anim.
  405.  
  406.      /         Single step forward one frame staying within anim.
  407.  
  408.      -         Increase animation playback speed.
  409.  
  410.      =         Decrease animation playback speed.
  411.  
  412.      0         Reset animation playback speed to original values.
  413.  
  414.      AUDIO RELATED WINDOW COMMANDS
  415.  
  416.      1           Decrement volume by 10.
  417.  
  418.      2           Decrement volume by 1.
  419.  
  420.      3           Increment volume by 1.
  421.  
  422.      4           Increment volume by 10.
  423.  
  424.      s           Toggle. Audio Volume(MUTE). on/off.
  425.  
  426.      8           Toggle. Main Speaker. on/off.
  427.  
  428.      9           Toggle. Headphones. on/off.
  429.  
  430.  
  431. MOUSE BUTTONS
  432.      Once the animation is up and running the mouse buttons  have
  433.      the following functions.
  434.  
  435.      <Left_Button>
  436.            Single step back one frame.
  437.  
  438.      <Middle_Button>
  439.            Toggle. starts/stops animation.
  440.  
  441.      <Right_Button>
  442.            Single step forward one frame.
  443.  
  444. BUFFERING, PIXMAPS and READ_FROM_FILE Options
  445.      XAnim by default will read the entire animation into memory.
  446.      DL,  PFX,  Moviesetter,  GIF  or URT RLE type animations are
  447.      always uncompressed  and  stored  in  memory  as  individual
  448.      images.
  449.  
  450.      For  the  AVI,  QT,  IFF,  FLI/FLC  animations,   only   the
  451.      compressed   delta   is   stored.   These  deltas  are  then
  452.      uncompressed each time they need to be displayed. The buffer
  453.      option(+b)  may  be used to potentially speed up playback by
  454.      uncompressing and storing these images ahead  of  time.  But
  455.      more memory is used up in the process.
  456.  
  457.      When an XPutImage is called, the image typically gets copied
  458.      twice,  once to memory and then from there onto the display.
  459.      A pixmap is directly copied onto  the  display  without  the
  460.      first  copy.  This is why it is sometimes much faster to use
  461.      the pixmap option(+p).  Each image isn't  converted  into  a
  462.      pixmap until the first time it is displayed. This is why the
  463.      first loop of an animation using this  option  is  sometimes
  464.      slower  than  subsequent  loops. While the pixmap option may
  465.      improve playback speed, it will slow things down if  on-the-
  466.      fly  scaling needs to be performed. This is because XAnim no
  467.      longer has direct access to the image and  needs  to  get  a
  468.      copy of it before it can be scaled.
  469.  
  470.      The read from file option(+f) causes xanim not to store  the
  471.      compressed  deltas in memory. Instead as each image is to be
  472.      displayed, xanim reads the  corresponding  compressed  delta
  473.      from  the  file, expands it and then displays it. While this
  474.      can dramatically cut down on  memory  usage,  the  necessary
  475.      reads  from  disk(or whatever) can slow down playback speed.
  476.      XAnim still needs to allocate one  to  three  image  buffers
  477.      depending  on  the type of animation and the scaling options
  478.      used. This option is only supported for AVI, QT, FLI/FLC and
  479.      IFF  animations.  The  BODY  chunk  of IFF animations is not
  480.      included in this. As a result, an IFF animation that is made
  481.      up  of  several  BODY chunks will not currently benefit from
  482.      this option.
  483.  
  484.  
  485. SCALING Options
  486.      There are two sets of scaling options. One set, the  display
  487.      scaling factors,  affects the size of the animation as it is
  488.      displayed. The other set, the buffer scaling factors, affect
  489.      the   size   of   the   images   as   they   are  stored  in
  490.      memory(buffered). The buffer  scaling  factors  only  affect
  491.      animations  that  are  buffered  and can greatly increase or
  492.      decrease memory usage.
  493.  
  494.      These two sets are completely independent of each other. You
  495.      can  set  the  buffer scaling factors to 20 times the normal
  496.      animation size and not affect the size at which that  anima-
  497.      tion  is  displayed.  The  images are stored at 20 times the
  498.      normal size(and at 400 times the memory usage), but then get
  499.      scaled  back  down  to  normal  size before being displayed.
  500.      NOTE: that an animation must be buffered in  order  for  the
  501.      buffer scaling factors to have any affect on it. The display
  502.      scaling factors affect all animations.
  503.  
  504.      You can create pixellation like  affects  by  buffering  the
  505.      animation  at  1/8 it's normal size, but keeping the display
  506.      scaling factors at the original size. (IE  "xanim  +bSS0.125
  507.      anim.anim").
  508.  
  509.      Many times it's faster to store  and  display  an  animation
  510.      with large dimensions at half-size. The option "+bSS0.5C" or
  511.      "+bSS0.5s0.5" both will accomplish this. To save memory, you
  512.      could  even store the animation at half size and yet display
  513.      it at full size. "+bSS0.5" will accomplish this.
  514.  
  515. FORWARDS, BACKWARDS and OPTIMIZATION.
  516.      Many type of animations(FLI/FLC/IFF/some AVI  and  QTs)  are
  517.      compressed  with  forward  playback in mind only. Each delta
  518.      only stores the difference between the current frame and the
  519.      previous frame. As a results, most of these animations don't
  520.      display correctly when played backwards.  Even when buffered
  521.      up, these may not work, since XAnim only stores the smallest
  522.      rectangle that encompasses the  changes  from  the  previous
  523.      frame.  You  can  force  XAnim  to store the entire frame by
  524.      specifying the "-o" option to turn  this  optimization  off.
  525.      This will most likely use more memory and slow down the ani-
  526.      mation, since more of the image needs to  be  stored  and/or
  527.      displayed.
  528.  
  529. COLOR OPTIONS
  530.      Most of this will be a TBD for a future rev and what's  here
  531.      might be sketchy, incomplete or just plain confusing.
  532.  
  533.      TrueColor and DirectColor displays don't need to worry about
  534.      most of these options, as the animations can be displayed in
  535.      their original colors(ignoring monitor variations etc). How-
  536.      ever,  TrueColor  and  DirectColor  displays  can't  display
  537.  
  538.      animations that employ color cycling  techniques  where  the
  539.      colormap  changes  from  frame  to frame.  DirectColor could
  540.      potentially support this, but not TrueColor.
  541.  
  542.      For the rest of the displays, the problem  becomes  matching
  543.      the  colors in the animations to the available colors of the
  544.      Display.  For  most  PseudoColor  displays  this  means  256
  545.      colors.  Many  of  which are already in use by various other
  546.      programs. XAnim defaults to creating it's own  colormap  and
  547.      using  all  the  colors  from  that. The window manager then
  548.      installs this new colormap, whenever the  mouse  pointer  is
  549.      inside  the  XAnim  animation  window(Sometimes  a  specific
  550.      action is required to change the ColorMap Focus, like click-
  551.      ing  in the window or pressing a specific key). In any case,
  552.      this action usually causes  all  the  other  colors  on  the
  553.      screen  to  be  temporarily  "messed-up"  until the mouse is
  554.      moved out of the animation window. The  alternative,  is  to
  555.      use  the  "+Cn"  option.  Now XAnim tries allocating all the
  556.      colors it needs from the current colormap. If it can't get a
  557.      certain color, then XAnim choose one that is "close" to this
  558.      certain color. Close is completely arbitrary. The  animation
  559.      is  now displayed in colors that are different than the ori-
  560.      ginal colors. This difference may or may not be noticeable.
  561.  
  562.      Another big problem is when the animations are what I called
  563.      TrueColor animations. Where each pixel is stored as RGB tri-
  564.      plets. For example, AVI 16 bit CRAM animations.  Each  pixel
  565.      has  5  bits of Red, 5 bits of Green and 5 bits of Blue info
  566.      associated with it. This means there  can  be  up  to  32768
  567.      unique  colors  in  each  image.  And  on  most  PseudoColor
  568.      displays we can only display 256 unique colors. Beside  get-
  569.      ting  better  displays,  what  can  we do? XAnim defaults to
  570.      truncating the RGB information from 555 to 332. That is to 3
  571.      bits  of  Red,  3  bits of Green and 2 bits of Blue. Less on
  572.      Blue because the human eye is  more  sensitive  to  Red  and
  573.      Green than Blue.  This 332 colormap happens to be 256 colors
  574.      in size, which nicely fits  in  with  our  display.  If  our
  575.      display  only  had  64 colors, then XAnim is smart enough to
  576.      truncate things down to 222. Now the problem is  the  colors
  577.      of the displayed anim are noticeably different than the ori-
  578.      ginal colors.  Typically you  can  see  color  banding  etc.
  579.      While  this  is fine to get a feel for the animation, we can
  580.      do better. One of the solutions XAnim  currently  offers  is
  581.      the "+bC1" option. What this does is choose the the best 256
  582.      colors from the first image  of  the  animation.  Then  each
  583.      pixel  of  each subsequent image is remapped to one of these
  584.      256 colors.  This takes up some CPU time up front  and  more
  585.      memory since each image needs to be buffered, but results in
  586.      a colors that are closer to the originals.  Another  option,
  587.      "+bCA",  chooses  the  best  256  from  each image, then 256
  588.      colors from all these colormaps  are  chosen  as  the  final
  589.      colormap.   This  is useful if the colors in the first image
  590.      aren't representative of the rest of the animation. This can
  591.      be  very  slow.  Another  option  that is supported, but not
  592.      really optimized for yet is "+bC3dm". This causes  XAnim  to
  593.      use  a  332 colormap and then apply a Floyd-Steinberg dither
  594.      algorithm to each image.  Currently this is very slow.  Dif-
  595.      ferent  dithers(like Ordered) and better optimizations might
  596.      speed this up  in  future  revs.  In  general,  handling  of
  597.      TrueColor animations in XAnim needs to be improved.
  598.  
  599.      Another scenario where colors need to be remapped,  is  when
  600.      several  images  or animations with different colormaps need
  601.      to be displayed.  Changing the colormap usually  results  in
  602.      an annoying flicker. One solution to this is to remap all of
  603.      the images/animations to the same colormap. The "+Ca" option
  604.      chooses  the  best  colors  from  all the colormaps and then
  605.      remaps all the images to it. The "+Cf" option, simply remaps
  606.      everything  to the first colormap.  The "+Ch" option is use-
  607.      ful when an animation's colormap specifies a lot  of  colors
  608.      that aren't used. XAnim looks through each buffered image of
  609.      the animation and makes a histogram of the  useage  of  each
  610.      color.  This  information  is then used to weedout unused or
  611.      rarely used colors.
  612.  
  613. QUICKTIME ANIMATIONS
  614.      Quicktime animations are  usually  stored  in  two  separate
  615.      files.  One is call a data fork and ends with a ".data". The
  616.      other is a resource fork and ends in  a  ".rsrc".  Sometimes
  617.      these  animations  are in a "flattened" format, where every-
  618.      thing is put into one file. There's no standard naming  for-
  619.      mat for these types of files.
  620.  
  621.      For example, if you have a quicktime animation  made  up  of
  622.      two  files  named:  "spin.rsrc"  and  "spin.data",   you can
  623.      display them using Xanim with either of the  following  com-
  624.      mands  "xanim  spin"  or  "xanim spin.rsrc".  XAnim is smart
  625.      enough to add/modfiy the  ".rsrc"  and  ".data"  endings  as
  626.      needed.
  627.  
  628.      If you use AUFS from the Columbia  Appletalk  Package,  then
  629.      Macintosh  files have their data fork stored in the expected
  630.      place, and the resource fork is in a file with the same name
  631.      in a  .resource subdirectory. Therefore, if the data fork is
  632.      in "spin", and the resource fork isin  ".resource/spin", the
  633.      movie can be displayed with "xanim spin".
  634.  
  635.      For "flattened" quicktime animations, you  need  to  specify
  636.      the entire file name.
  637.  
  638.      NOTE: XAnim may not support all SMC or RPZA quicktime anima-
  639.      tions. It'll print "unknown code variation XX" to the screen
  640.      as it encounters these and move on to the next image of that
  641.      animation.
  642.  
  643.  
  644. EXAMPLES:
  645.     To display a single animation with Audio:
  646.  
  647.         xanim +Ae car_race.avi
  648.  
  649.     To display a audio animation on Sparc. main speakers off
  650.     and  headphones on:
  651.  
  652.         xanim +Aep1 -Ap0 car_race.avi
  653.  
  654.     To display a single animation:
  655.  
  656.         xanim iff3.anim
  657.  
  658.     To display a nonlooping IFF animation:
  659.  
  660.         xanim +c iff3.anim
  661.  
  662.     To display A.fli 3 times, B.anim and C.movie 2 times each and D.fli
  663.     once before repeating:
  664.  
  665.         xanim -l3 A.fli -l2 B.anim C.movie -l1 D.fli
  666.  
  667.     To see A.anim real slow(2 seconds for each frame):
  668.  
  669.         xanim +j2000 A.anim
  670.  
  671.     To display title image for a while then run an animation at
  672.     normal speed:
  673.  
  674.         xanim +j2000 title.gif +j0 anim.gifanim
  675.  
  676.  
  677. A series of GIF's can be displayed as:
  678.  
  679.     xanim im_0.gif im_1.gif im_2.gif ... im_36.gif
  680.  
  681.  or
  682.  
  683.     xanim im_*.gif
  684.  
  685.  or
  686.  
  687.     xanim im.txt
  688.  
  689.  or
  690.  
  691.     xanim im.gifanim
  692.  
  693. where im.txt is a txt file(a list of images, see xanim.doc for more details).
  694. and im.gifanim is one gif file composed of im_0.gif through im_36.gif.
  695. (see txtmerge to create a single gif file from a txt file).
  696.  
  697. X11 Notes:
  698. --------------------------------------
  699.  I. X11 Server Options
  700.  
  701.    When XAnim opens the display it passes the argument list to X11 which
  702.    then filters off the arguments it recognizes. XAnim won't even see these
  703.    arguments(which is sometimes a problem). For instance
  704.  
  705.    xa -geom =+100+100 skier.fli
  706.  
  707.    will play the anim skier.fli at pos <100,100> on the X11 screen.  Or
  708.  
  709.    xa -display nantucket:0.0 skier.fli
  710.  
  711.    will display the anim skier.fli on the machine nantucket's display.
  712.  
  713.    Sometimes this is a problem, because a valid XAnim option is stripped by the
  714.    X11 server. For instance if +r was being stripped, then use ++r instead.
  715.    Same goes with -r. Use --r instead if you believe it's being filtered
  716.    by X11.
  717.  
  718. Machine Specific and Compiler Notes:
  719. --------------------------------------
  720.  Some PC's need you to uncomment the line below in Makefile.
  721.  #XA_INET_LIB = -linet
  722.  
  723.  Depending on your window manager(mwm,uwm,olwm,twm etc), you might
  724.  want to have XAnim do a XInstallColormap. This shouldn't be necessary
  725.  for most workstations and can cause core dumps on some PCs.
  726.  There are usually user selectable options for each window manager
  727.  that selects the colormap focus policy(pointer,fixed,explicit etc).
  728.  Use -DNO_INSTALL in Makefile if you DON't want XAnim to install
  729.  the colormap.
  730.  
  731.  Some X11's don't have support for multiple visuals.  An executable
  732.  compiled with such an X11 will not be able to correctly run on a
  733.  machine that does supports multiple visuals even if they're binary
  734.  compatible.
  735.  
  736.  Hugh D.R. Evans has supplied make.com, xanim.opt and added VMS defines
  737.  so that VMS users may compile and run XAnim. Rick Dyson has provided
  738.  the descript.mms file and some VMS fixes. John Kneitz has also
  739.  provide some VMS fixes and suggestions.
  740.  
  741. And Yet More Notes about Quicktime Animations
  742. ---------------------------------------------
  743.         NOTES ON QUICKTIME ANIMATIONS WITH XANIM
  744.  
  745.   (these are just my notes and may contain some inconsistencies.
  746.    There's currently some question about the true meaning of
  747.    "flatten". It might just mean taking a quicktime file and
  748.    replacing a references to another files with those files
  749.    themselves.  But lately many people use it to mean collapsing
  750.    the *.data and *.rsrc forks into one *.data fork for export
  751.    to a non-mac computer. - Mark)
  752.  
  753.  
  754.    EXTRACTING Quicktime Animations
  755.  
  756.     Typically you will obtain the quicktime animations that have
  757.     been archived and then binhex'd. If the file you have ends
  758.     in a .hqx, then you need to run hexbin on it ("hexbin anim.hqx").
  759.     This will create a *.bin file(not necessarily anim.bin, it
  760.     could be anything.bin. The actual name is contained within
  761.     the *.hqx file).  
  762.  
  763.     If the file you have ends in a .bin or you've just hexbin'd a file, 
  764.     now you need to unpack it. In other words extract the files that
  765.     are contained within it. These files can be programs/documents/
  766.     animations/images etc. They're not necessarily quicktime animations.
  767.  
  768.     There is a program called macunpack that should be used to
  769.     accomplish this. You need to use the -f option, I recommend
  770.     the -lv options as well. (ie "macunpack -flv file.bin")
  771.  
  772.     Macunpack doesn't support certain DiskDoubler or Stuffit Deluxe
  773.     archives. There is no unix/pc program that I know of that does(except 
  774.     for the Mac). In this case your only choice is to get a hold of a 
  775.     Macintosh computer and someone who knows how to use it and
  776.     hopefully some method of transferring files to/from it.
  777.  
  778.     Once you've unpacked everything, you should have three files,
  779.     a *.info, a *.rsrc and a *.data. You can delete the *.info file.
  780.     XAnim doesn't need or use it.
  781.  
  782.     The quicktime animation is made up of BOTH the *.rsrc and the
  783.     *.data files and therefore XAnim needs BOTH the *.rsrc and the 
  784.     *.data in order to recognize and display the animation.
  785.   
  786.     The only exception to this is if the animation has been "flattened".
  787.     Essentially, all that this means is that the .rsrc and .data files
  788.     were merged into one file for export to a non-mac computer.
  789.     This file doesn't have any real naming conventions, but it is
  790.     usually something like .mov, .mv, .qt, etc(it is never .bin or .hqx). 
  791.     And it is rarely .data. If XAnim can't play it, then it's 95%
  792.     likely to be a *.data fork(that's missing a *.rsrc fork) and not
  793.     a flattened quicktime animation.
  794.  
  795.     Macunpack and hexbin can be found in the macutil archive. They
  796.     are available at the following locations:
  797.  
  798.         sumex-aim.stanford.edu:/info-mac/unix/macutil-20b1.shar
  799.         ftp.cwi.nl:/pub/macutil2.0b3.shar.Z
  800.         solaris.ims.ac.jp:/pub/unix/mac/macutil-20b1.shar
  801.  
  802.     Use archie to find other sites.
  803.  
  804.     Here's a quick blurb on macutils from the readme.
  805.  
  806.             o hexbin - a program to convert BinHex 4.0 to MacBinary;
  807.           it also converts uuencode (and UULite) files to their
  808.           native binary format; support for .dl, .hex, and .hcx
  809.           formats (all predecessors of BinHex 4.0) also exists
  810.  
  811.             o macunpack - a program to unpack PackIt, StuffIt,
  812.           Diamond, Compactor/Compact Pro, most StuffIt Classic
  813.           and StuffIt Deluxe, DiskDoubler, Zoom and LHarc/MacLHa
  814.           archives.
  815.  
  816.           It also decodes BinHex 5.0, MacBinary, uuencode, and
  817.           UNIX compress (ie: .Z suffix) files (as well as variants
  818.           of compress implemented by various Macintosh compress
  819.           programs).
  820.  
  821.  
  822.   TRANSFERING DIRECTLY FROM A MACINTOSH
  823.  
  824.     If you are transferring a quicktime animation directly from a 
  825.     Macintosh(ftp/fetch/gator/etc), you need to use the MacBinary mode.
  826.     This will archive all three resource forks(.info,.rsrc and .data) 
  827.     into a .bin file and transfer that. You must then use "macunpack -flv"
  828.     as described above.
  829.   
  830.     If you use Binary mode(as opposed to the MacBinary mode), ONLY the 
  831.     *.data file will be transferred. This *.data file is useless without
  832.     the *.rsrc file, unless it happens to be "flattened". If you don't
  833.     absolutely know this to be true, then use the MacBinary mode and 
  834.     extract with macunpack.
  835.  
  836.  
  837.   OTHER PROGRAMS
  838.  
  839.     mcvert is also capable of extracting the *.rsrc and *.data files
  840.     form a MacBinary file(*.bin). It doesn't support all of the
  841.     archival compression formats that macunpack does and I'm not
  842.     as familiar with it. Archie should be able to find it.
  843.  
  844.   CREATING A QUICKTIME FOR EXPORT ON A MACINTOSH
  845.  
  846.     Movieconverter, part of Apple's Quicktime Starter Kit (a commercial product)
  847.     can do this.  Save the movie as BOTH "Make self-contained" and "Playable
  848.     on non-Apple computers." 
  849.  
  850.  
  851.   If you have any other questions or problems trying to run 
  852.   quicktime animation using xanim I might be able to answer
  853.   them.
  854.  
  855. ------------------------------------------------------------------------------
  856.  
  857. Mark Podlipec  podlipec@wellfleet.com
  858. http://www.portal.com/~podlipec/home.html  "The XAnim Home Page"
  859.